docs: Document how to fetch additional branches #10795
Conversation
Tools like reno depend on a complete git history. Simply unshallowing a clone is not sufficient, as we specifically fetch from the branch or tag that we are building docs for, e.g.: git fetch origin --force --prune --prune-tags --depth 50 refs/heads/main:refs/remotes/origin/main Add documentation describing how you can correct this if necessary. Signed-off-by: Stephen Finucane <[email protected]>
| jobs: | ||
| post_checkout: | ||
| - git fetch --unshallow || true | ||
| - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true |
There was a problem hiding this comment.
Why is this line required? Seems pretty specific to a use case, and something I'd expect git to do by default?
There was a problem hiding this comment.
This is necessary because we're configuring git to only fetch a single branch in this command (which you'll see a variant of in all builds):
git fetch origin --force --prune --prune-tags --depth 50 refs/heads/main:refs/remotes/origin/main
If you shallow clone a repo then run the above locally and look at .git/config, you'll see something like the following:
[remote "origin"]
fetch = +refs/heads/main:refs/remotes/origin/main
Which means "map the main ref locally to the main remote ref". Because we've limited fetch to a single branch, we will always get just that single branch no matter what flags we pass. To fix this, you need to tell git to fetch all branches and map them to the same name locally, which is what we're doing here.
Perhaps there's another way to override the config file during a fetch operation, but if there is I'm not aware of it.
There was a problem hiding this comment.
Oh, and as I mentioned in the blurb beforehand, you'll need to do this if you have a tool that needs access to other branches rather than just other tags.
Tools like reno depend on a complete git history. Simply unshallowing a clone is not sufficient, as we specifically fetch from the branch or tag that we are building docs for, e.g.:
Add documentation describing how you can correct this if necessary.
📚 Documentation previews 📚
docs): https://docs--10795.org.readthedocs.build/en/10795/dev): https://dev--10795.org.readthedocs.build/en/10795/